IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/u_man/cat1/pmlc.z/pmlc

Text File | 1998-10-20 | 18KB | 328 lines

PPPPMMMMLLLLCCCC((((1111))))                                                                PPPPMMMMLLLLCCCC((((1111))))



NNNNAAAAMMMMEEEE
     ppppmmmmllllcccc - configure active Performance Co-Pilot pmlogger(s) interactively

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ppppmmmmllllcccc [----eeee] [----hhhh _h_o_s_t] [----iiii] [----nnnn _p_m_n_s_f_i_l_e] [----PPPP] [----pppp _p_o_r_t] [----ZZZZ _t_i_m_e_z_o_n_e] [----zzzz]
     [ppppiiiidddd]

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     ppppmmmmllllcccc may be used to change those metrics and instances which a
     ppppmmmmllllooooggggggggeeeerrrr(1) writes to a Performance Co-Pilot archive (see PPPPCCCCPPPPIIIInnnnttttrrrroooo(1)),
     the frequency with which the metrics are collected and whether the
     logging is mandatory, advisory, on or off.  It also reports the current
     logging status of metrics and instances.  ppppmmmmllllcccc may be used to control
     pmlogger instances on remote hosts as well as those on the local host.

     Normally ppppmmmmllllcccc operates on the distributed Performance Metrics Name Space
     (PMNS), however if the ----nnnn option is specified an alternative local PMNS
     is loaded from the file _p_m_n_s_f_i_l_e.

     If the ----PPPP option is specified, ppppmmmmllllcccc will attempt to start with a
     connection to the primary pmlogger on the local host.  If the ----pppp option
     is specified, then ppppmmmmllllcccc will attempt to start with a connection to the
     pmlogger on this TCP/IP _p_o_r_t.  Alternatively, if _p_i_d is specified, a
     connection to the pmlogger instance with that process id will be
     attempted on startup.  The ----hhhh option may only be used if ----PPPP,,,, ----pppp _p_o_r_t or a
     _p_i_d is also specified.  In that case ppppmmmmllllcccc will initially connect to the
     specified (remote) pmlogger instance on _h_o_s_t rather than the local host.
     If the connection to the specified pmlogger instance cannot be
     established, ppppmmmmllllcccc will start with no connection.  These options typically
     allow the same file of ppppmmmmllllcccc commands to be directed to multiple pmlogger
     instances by varying the command line arguments.  Note that ----PPPP, ----pppp _p_o_r_t,
     _p_i_d and ----hhhh are used only when making an initial connection to a pmlogger
     instance.  They are not used as defaults if subsequent connections are
     made interactively (see the ccccoooonnnnnnnneeeecccctttt command below).

     By default, ppppmmmmllllcccc reports the time of day according to the local timezone
     on the system where ppppmmmmllllcccc is run.  The ----ZZZZ option changes the timezone to
     _t_i_m_e_z_o_n_e in the format of the environment variable TTTTZZZZ as described in
     eeeennnnvvvviiiirrrroooonnnn(5).  The ----zzzz option changes the timezone to the timezone of the
     pmlogger instance from which information is being obtained.  Only one of
     ----zzzz or ----ZZZZ may be specified.

     If standard input is from a tty, ppppmmmmllllcccc is interactive, with prompts.  The
     ----iiii flag may be used to force interactive behavior, and is typically used
     in conjunction with ----eeee to echo all command input on standard output.

     The following commands may be used:

     sssshhhhoooowwww [ llllooooggggggggeeeerrrrssss ] [ @@@@_h_o_s_t ]
         Displays the process identities of all pmlogger instances running on
         the local host (or _h_o_s_t, if specified).  The primary pmlogger pid is
         parenthesized because it can be referred to as "primary" as well as



                                                                        PPPPaaaaggggeeee 1111






PPPPMMMMLLLLCCCC((((1111))))                                                                PPPPMMMMLLLLCCCC((((1111))))



         by its pid.

     ccccoooonnnnnnnneeeecccctttt _p_i_d [ @@@@_h_o_s_t ]
     ccccoooonnnnnnnneeeecccctttt pppprrrriiiimmmmaaaarrrryyyy [ @@@@_h_o_s_t ]
         Connects ppppmmmmllllcccc to the specified pmlogger process.  Any existing
         connection to a pmlogger instance is closed first.  Each pmlogger
         instance will accept at most one connection at a time, so if the
         connection is successfully established, your ppppmmmmllllcccc will be the only
         one controlling the pmlogger instance it is connected to.

     nnnneeeewwww vvvvoooolllluuuummmmeeee
         This command works only while a connection to a pmlogger instance is
         established.  It tells the pmlogger to close the current volume of
         the log and open a new volume.  Closed volumes may be archived, e.g.
         as part of a regular log management procedure to control the size of
         the physical log files.

     ssssttttaaaattttuuuussss
         This command works only while a connection to a pmlogger instance is
         established.  It prints information about the state of the pmlogger
         instance and its associated log.

     ttttiiiimmmmeeeezzzzoooonnnneeee llllooooccccaaaallll | llllooooggggggggeeeerrrr | """"_t_i_m_e_z_o_n_e""""
         This command sets the time zone used when times are printed.  llllooooccccaaaallll
         means use the time zone of the machine that ppppmmmmllllcccc is running on.
         llllooooggggggggeeeerrrr means use the time zone of the machine where the pmlogger
         instance is running.  Alternatively an explicit _t_i_m_e_z_o_n_e enclosed in
         quotes may be supplied (refer to TTTTZZZZ in eeeennnnvvvviiiirrrroooonnnn(5) for details).  The
         default time zone is llllooooccccaaaallll unless one of the ----zzzz or ----ZZZZ options has
         been supplied on the command line.

     fffflllluuuusssshhhh
         This command works only while a connection to a pmlogger instance is
         established, and requests the pmlogger instance to flush to disk all
         buffers associated with the current archive.  For old-timers, ssssyyyynnnncccc is
         a synonym for fffflllluuuusssshhhh.

     hhhheeeellllpppp
         Displays a summary of the available commands.
         hhhh and ???? are synonyms for hhhheeeellllpppp.

     qqqquuuuiiiitttt
         Exits from ppppmmmmllllcccc.

     The remaining commands query and change the logging state of metrics and
     instances.  They will work only if ppppmmmmllllcccc has a connection to a pmlogger
     instance.  Metrics may be specified as fully qualified names (e.g.
     hinv.ncpu) or subtrees of the PMNS (e.g. hinv) which are expanded to
     include all metrics in the subtree (e.g. hinv.ncpu, hinv.cpuclock, etc.).
     Lists of metrics may be specified by enclosing them in braces with spaces
     or a comma between metrics (e.g. {hinv.ncpu hinv.ndisk}).  Subtrees of
     metrics may be included in such lists.


                                                                        PPPPaaaaggggeeee 2222






PPPPMMMMLLLLCCCC((((1111))))                                                                PPPPMMMMLLLLCCCC((((1111))))



     Each individual metric specification may be further qualified with a
     space or comma separated list of instances in square brackets (e.g.
     irix.kernel.all.load["1 minute", "5 minute"]).  External instance names
     or numeric internal instance identifiers or both may be used in the same
     list (e.g. sample.colour.[red,1,"blue"]).  If an instance qualification
     is applied to a subtree of the PMNS all of the metrics in the subtree
     must have the same instance domain.  Instance qualifications may not be
     applied to entire lists of metrics but may appear inside such lists.

     If no instances are specified for a metric, all instances are used.  All
     instances means all instances available at the time the pmlogger instance
     in question fetches the metrics for logging.  If an instance domain
     changes over time this is not always the same as the set of instances
     displayed by ppppmmmmllllcccc, which can only display the currently available
     instances.  To prevent unintentional errors, only the instances that are
     currently available to ppppmmmmllllcccc may appear in instance specifications.

     qqqquuuueeeerrrryyyy _m_e_t_r_i_c_l_i_s_t
         The current logging state of each metric (and instances, where
         applicable) in _m_e_t_r_i_c_l_i_s_t is displayed.  This includes the logging
         state (e.g. on, maybe, off) and the logging interval for each metric
         (and instance) requested.  The following abbreviations pertaining to
         metrics (and instances) may appear in the output:  aaaaddddvvvv, advisory;
         mmmmaaaannnndddd, mandatory; nnnnllll, not in the log; nnnnaaaa, in the log but not currently
         available from its Performance Metrics Domain Agent (PMDA).  Where
         appropriate, an instance name will appear last on a line preceded by
         its numeric internal instance identifier.

     [ lllloooogggg ] mmmmaaaannnnddddaaaattttoooorrrryyyy oooonnnn _i_n_t_e_r_v_a_l _m_e_t_r_i_c_l_i_s_t
         This form of the lllloooogggg command turns on logging for the metrics (and
         any instances) in _m_e_t_r_i_c_l_i_s_t.  _i_n_t_e_r_v_a_l specifies how often the
         specified metrics/instances should be logged.  oooonnnncccceeee indicates that
         the metrics/instances should appear at most once in the log.  More
         often one would use the optional keyword eeeevvvveeeerrrryyyy followed by a positive
         number and one of mmmmiiiilllllllliiiisssseeeeccccoooonnnndddd (or mmmmsssseeeecccc), sssseeeeccccoooonnnndddd (or sssseeeecccc), mmmmiiiinnnnuuuutttteeee (or
         mmmmiiiinnnn), hhhhoooouuuurrrr or their plurals.
         Note that the keyword ddddeeeeffffaaaauuuulllltttt which may be used for the default
         _i_n_t_e_r_v_a_l in a ppppmmmmllllooooggggggggeeeerrrr(1) configuration file cannot be used in ppppmmmmllllcccc.
         Internal limitations require the _i_n_t_e_r_v_a_l to be less than
         (approximately) 74 hours.  An _i_n_t_e_r_v_a_l value of zero is a synonym for
         oooonnnncccceeee.

     [ lllloooogggg ] mmmmaaaannnnddddaaaattttoooorrrryyyy ooooffffffff _m_e_t_r_i_c_l_i_s_t
         This tells the pmlogger instance not to log any of the
         metrics/instances in _m_e_t_r_i_c_l_i_s_t.

     [ lllloooogggg ] mmmmaaaannnnddddaaaattttoooorrrryyyy mmmmaaaayyyybbbbeeee _m_e_t_r_i_c_l_i_s_t
         This tells the pmlogger instance to honor any subsequent advisory
         logging requests for the metrics/instances in _m_e_t_r_i_c_l_i_s_t.  If the
         current logging state of the metrics/instances is mandatory (either
         on or off) the new state will be set to maybe (effectively advisory



                                                                        PPPPaaaaggggeeee 3333






PPPPMMMMLLLLCCCC((((1111))))                                                                PPPPMMMMLLLLCCCC((((1111))))



         off).  If the current state of the metrics/instances is already
         advisory (either on or off) the state(s) for the metrics/instances
         will remain as they are.

     [ lllloooogggg ] aaaaddddvvvviiiissssoooorrrryyyy oooonnnn _i_n_t_e_r_v_a_l _m_e_t_r_i_c_l_i_s_t
     [ lllloooogggg ] aaaaddddvvvviiiissssoooorrrryyyy ooooffffffff _m_e_t_r_i_c_l_i_s_t
         Advisory logging is only applicable if the last logging state
         specified for a metric/instance was "mandatory maybe" (which permits
         subsequent advisory logging control) or if the logging state is
         already advisory.  These two statements turn advisory logging on or
         off (respectively) for the specified metrics/instances.
         The interpretation for _i_n_t_e_r_v_a_l is as above for the mmmmaaaannnnddddaaaattttoooorrrryyyy case.

     There is no continuation character required for commands that span lines.

     The word aaaatttt may be used interchangeably with @@@@.

     A request to log all instances of a metric will supersede any prior
     request to log either all or specific instances of a metric (if the
     request specifies a permissible transition in the logging state).  A
     request to log specific instances of a metric when all instances of a
     metric are already being logged is refused by ppppmmmmllllooooggggggggeeeerrrr.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     PPPPCCCCPPPPIIIInnnnttttrrrroooo(1), ppppmmmmccccdddd(1), ppppmmmmllllooooggggggggeeeerrrr(1), ppppmmmmdddduuuummmmpppplllloooogggg(1) and eeeennnnvvvviiiirrrroooonnnn(5).

DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     Most error or warning messages are self-explanatory.  A message of the
     form
             Warning: unable to change logging state for...
     followed by a list of metrics (and possibly instances) indicates that
     ppppmmmmllllooooggggggggeeeerrrr refused the request for the metrics (and instances) that appear.
     Any metrics (and instances) that were specified but do not appear in the
     message have had their logging state updated successfully (no news is
     good news).  Usually this warning results from requesting advisory
     logging when a mandatory control is already in place, or requesting
     logging for specific instances when all instances are already being
     logged.

CCCCAAAAVVVVEEEEAAAATTTT
     If all instances of a metric are being logged and a request is made to
     log specific instances of the metric with the same state and frequency,
     the request may appear to succeed, even though ppppmmmmllllooooggggggggeeeerrrr has refused the
     request.  This is not normally a problem, as the required information
     will still be placed into the log by ppppmmmmllllooooggggggggeeeerrrr.

     However in the case where the metric is to be logged once, the outcome is
     not what might be expected.  When ppppmmmmllllooooggggggggeeeerrrr receives a request to log a
     metric once, it places the current value(s) of the metric into the log as
     soon as it can, regardless of whether the metric is already in the log.
     This may be used to force values into the log.  When a request to log
     specific instances of a metric arrives and is refused because all


                                                                        PPPPaaaaggggeeee 4444






PPPPMMMMLLLLCCCC((((1111))))                                                                PPPPMMMMLLLLCCCC((((1111))))



     instances of the metric are already being logged, ppppmmmmllllooooggggggggeeeerrrr does not place
     values for the instances requested into the log.  It returns the current
     logging state for each instance requested to ppppmmmmllllcccc.  The requested and
     returned states are identical, so ppppmmmmllllcccc doesn't raise an error as it
     should.

     To ensure that only certain instances of a metric are being logged, one
     should always turn off logging for all instances of the metric prior to
     turning on logging for the specific instances required.














































                                                                        PPPPaaaaggggeeee 5555